basic-memory

--- title: 'SPEC-1: Specification-Driven Development Process' type: spec permalink: specs/spec-1-specification-driven-development-process tags: - process - specification - development - meta --- # SPEC-1: Specification-Driven Development Process ## Why We're implementing specification-driven development to solve the complexity and circular refactoring issues in our web development process. Instead of getting lost in framework details and type gymnastics, we start with clear specifications that drive implementation. The default approach of adhoc development with AI agents tends to result in: - Circular refactoring cycles - Fighting framework complexity - Lost context between sessions - Unclear requirements and scope ## What This spec defines our process for using basic-memory as the specification engine to build basic-memory-cloud. We're creating a recursive development pattern where basic-memory manages the specs that drive the development of basic-memory-cloud. **Affected Areas:** - All future component development - Architecture decisions - Agent collaboration workflows - Knowledge management and context preservation ## How (High Level) ### Specification Structure Name: Spec names should be numbered sequentially, followed by a description eg. `SPEC-X - Simple Description.md`. See: [[Spec-2: Slash Commands Reference]] Every spec is a complete thought containing: - **Why**: The reasoning and problem being solved - **What**: What is affected or changed - **How**: High-level approach to implementation - **How to Evaluate**: Testing/validation procedure - Additional context as needed ### Living Specification Format Specifications are **living documents** that evolve throughout implementation: **Progress Tracking:** - **Completed items**: Use ✅ checkmark emoji for implemented features - **Pending items**: Use `- [ ]` GitHub-style checkboxes for remaining tasks - **In-progress items**: Use `- [x]` when work is actively underway **Status Philosophy:** - **Avoid static status headers** like "COMPLETE" or "IN PROGRESS" that become stale - **Use checklists within content** to show granular implementation progress - **Keep specs informative** while providing clear progress visibility - **Update continuously** as understanding and implementation evolve **Example Format:** ```markdown ### ComponentName - ✅ Basic functionality implemented - ✅ Props and events defined - - [ ] Add sorting controls - - [ ] Improve accessibility - - [x] Currently implementing responsive design ``` This creates **git-friendly progress tracking** where `[ ]` easily becomes `[x]` or ✅ when completed, and specs remain valuable throughout the development lifecycle. ## Claude Code We will leverage Claude Code capabilities to make the process semi-automated. - Slash commands: define repeatable steps in the process (create spec, implement, review, etc) - Agents: define roles to carry out instructions (front end developer, baskend developer, etc) - MCP tools: enable agents to implement specs via actions (write code, test, etc) ### Workflow 1. **Create**: Write spec as complete thought in `/specs` folder 2. **Discuss**: Iterate and refine through agent collaboration 3. **Implement**: Hand spec to appropriate specialist agent 4. **Validate**: Review implementation against spec criteria 5. **Document**: Update spec with learnings and decisions ### Slash Commands Claude slash commands are used to manage the flow. These are simple instructions to help make the process uniform. They can be updated and refined as needed. - `/spec create [name]` - Create new specification - `/spec status` - Show current spec states - `/spec implement [name]` - Hand to appropriate agent - `/spec review [name]` - Validate implementation ### Agent Orchestration Agents are defined with clear roles, for instance: - **system-architect**: Creates high-level specs, ADRs, architectural decisions - **vue-developer**: Component specs, UI patterns, frontend architecture - **python-developer**: Implementation specs, technical details, backend logic - - Each agent reads/updates specs through basic-memory tools. ## How to Evaluate ### Success Criteria - Specs provide clear, actionable guidance for implementation - Reduced circular refactoring and scope creep - Persistent context across development sessions - Clean separation between "what/why" and implementation details - Specs record a history of what happened and why for historical context ### Testing Procedure 1. Create a spec for an existing problematic component 2. Have an agent implement following only the spec 3. Compare result quality and development speed vs. ad-hoc approach 4. Measure context preservation across sessions 5. Evaluate spec clarity and completeness ### Metrics - Time from spec to working implementation - Number of refactoring cycles required - Agent understanding of requirements - Spec reusability for similar components ## Notes - Start simple: specs are just complete thoughts, not heavy processes - Use basic-memory's knowledge graph to link specs, decisions, components - Let the process evolve naturally based on what works - Focus on solving the actual problem: Manage complexity in development ## Observations - [problem] Web development without clear goals and documentation circular refactoring cycles #complexity - [solution] Specification-driven development reduces scope creep and context loss #process-improvement - [pattern] basic-memory as specification engine creates recursive development loop #meta-development - [workflow] Five-step process: Create → Discuss → Implement → Validate → Document #methodology - [tool] Slash commands provide uniform process automation #automation - [agent-pattern] Three specialized agents handle different implementation domains #specialization - [success-metric] Time from spec to working implementation measures process efficiency #measurement - [learning] Process should evolve naturally based on what works in practice #adaptation - [format] Living specifications use checklists for progress tracking instead of static status headers #documentation - [evolution] Specs evolve throughout implementation maintaining value as working documents #continuous-improvement ## Relations - spec [[Spec-2: Slash Commands Reference]] - spec [[Spec-3: Agent Definitions]]